home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / TextField.java < prev    next >
Text File  |  1998-09-22  |  14KB  |  468 lines
  1. /*
  2.  * @(#)TextField.java    1.46 98/08/13
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14. package java.awt;
  15.  
  16. import java.awt.peer.TextFieldPeer;
  17. import java.awt.event.*;
  18. import java.io.ObjectOutputStream;
  19. import java.io.ObjectInputStream;
  20. import java.io.IOException;
  21.  
  22.  
  23. /**
  24.  * A <code>TextField</code> object is a text component 
  25.  * that allows for the editing of a single line of text.
  26.  * <p>
  27.  * For example, the following image depicts a frame with four
  28.  * text fields of varying widths. Two of these text fields
  29.  * display the predefined text <code>"Hello"</code>.
  30.  * <p>
  31.  * <img src="images-awt/TextField-1.gif"
  32.  * ALIGN=center HSPACE=10 VSPACE=7>
  33.  * <p>
  34.  * Here is the code that produces these four text fields:
  35.  * <p>
  36.  * <hr><blockquote><pre>
  37.  * TextField tf1, tf2, tf3, tf4; 
  38.  * // a blank text field
  39.  * tf1 = new TextField();
  40.  * // blank field of 20 columns
  41.  * tf2 = new TextField("", 20);
  42.  * // predefined text displayed
  43.  * tf3 = new TextField("Hello!");
  44.  * // predefined text in 30 columns
  45.  * tf4 = new TextField("Hello", 30);
  46.  * </pre></blockquote><hr>
  47.  * <p>
  48.  * Every time the user types a key in the text field, AWT 
  49.  * sends two action events to the text field. The first 
  50.  * one represents the key press and the second one, 
  51.  * the key release. Each action event embodies the state 
  52.  * of the system at the time that some action occurred.
  53.  * The properties of an action event indicate which 
  54.  * key was pressed, what modifier keys were also pressed,
  55.  * and the time at which the event occurred. 
  56.  * <p>
  57.  * Since the event is an instance of <code>ActionEvent</code>, 
  58.  * the <code>TextField</code> class's <code>processEvent</code> 
  59.  * method examines the event and passes it along to 
  60.  * <code>processActionEvent</code>. The latter method redirects the
  61.  * event to any <code>ActionListener</code> objects that have
  62.  * registered an interest in action events generated by this
  63.  * text field. 
  64.  *
  65.  * @version    1.46, 08/13/98
  66.  * @author     Sami Shaio
  67.  * @see         java.awt.event.ActionEvent
  68.  * @see         java.awt.TextField#processEvent
  69.  * @see         java.awt.TextField#processActionEvent
  70.  * @since       JDK1.0
  71.  */
  72. public class TextField extends TextComponent {
  73.  
  74.     /**
  75.      * The number of columns in the TextField.
  76.      */
  77.     int columns;
  78.  
  79.     /**
  80.      * The echo character.
  81.      */
  82.     char echoChar;
  83.  
  84.     transient ActionListener actionListener;
  85.  
  86.     private static final String base = "textfield";
  87.     private static int nameCounter = 0;
  88.  
  89.     /*
  90.      * JDK 1.1 serialVersionUID 
  91.      */
  92.     private static final long serialVersionUID = -2966288784432217853L;
  93.  
  94.     /**
  95.      * Constructs a new text field.
  96.      * @since      JDK1.0
  97.      */
  98.     public TextField() {
  99.     this("", 0);
  100.     }
  101.  
  102.     /**
  103.      * Constructs a new text field initialized with the specified text.
  104.      * @param      text       the text to be displayed.
  105.      * @since      JDK1.0
  106.      */
  107.     public TextField(String text) {
  108.     this(text, text.length());
  109.     }
  110.  
  111.     /**
  112.      * Constructs a new empty TextField with the specified number of columns.
  113.      * @param columns the number of columns
  114.      */ 
  115.     public TextField(int columns) {
  116.     this("", columns);
  117.     }
  118.  
  119.     /**
  120.      * Constructs a new text field initialized with the specified text
  121.      * to be displayed, and wide enough to hold the specified 
  122.      * number of characters.
  123.      * @param      text       the text to be displayed.
  124.      * @param      columns    the number of characters.
  125.      * @since      JDK1.0
  126.      */
  127.     public TextField(String text, int columns) {
  128.     super(text);
  129.     this.columns = columns;
  130.     }
  131.  
  132.     /**
  133.      * Construct a name for this component.  Called by getName() when the
  134.      * name is null.
  135.      */
  136.     String constructComponentName() {
  137.         return base + nameCounter++;
  138.     }
  139.  
  140.     /**
  141.      * Creates the TextField's peer.  The peer allows us to modify the
  142.      * appearance of the TextField without changing its functionality.
  143.      */
  144.     public void addNotify() {
  145.       synchronized (getTreeLock()) {
  146.     if (peer == null)
  147.         peer = getToolkit().createTextField(this);
  148.     super.addNotify();
  149.       }
  150.     }
  151.  
  152.     /**
  153.      * Gets the character that is to be used for echoing.
  154.      * <p>
  155.      * An echo character is useful for text fields where 
  156.      * user input should not be echoed to the screen, as in 
  157.      * the case of a text field for entering a password.
  158.      * @return      the echo character for this text field.
  159.      * @see         java.awt.TextField#echoCharIsSet
  160.      * @see         java.awt.TextField#setEchoChar
  161.      * @since       JDK1.0
  162.      */
  163.     public char getEchoChar() {
  164.     return echoChar;
  165.     }
  166.  
  167.     /**
  168.      * Sets the echo character for this text field. 
  169.      * <p>
  170.      * An echo character is useful for text fields where 
  171.      * user input should not be echoed to the screen, as in 
  172.      * the case of a text field for entering a password.
  173.      * @param       c   the echo character for this text field.
  174.      * @see         java.awt.TextField#echoCharIsSet
  175.      * @see         java.awt.TextField#getEchoChar
  176.      * @since       JDK1.1
  177.      */
  178.     public void setEchoChar(char c) {
  179.     setEchoCharacter(c);
  180.     }
  181.  
  182.     /**
  183.      * @deprecated As of JDK version 1.1,
  184.      * replaced by <code>setEchoChar(char)</code>.
  185.      */
  186.     public synchronized void setEchoCharacter(char c) {
  187.     echoChar = c;
  188.     TextFieldPeer peer = (TextFieldPeer)this.peer;
  189.     if (peer != null) {
  190.         peer.setEchoCharacter(c);
  191.     }
  192.     }
  193.  
  194.     /**
  195.      * Indicates whether or not this text field has a 
  196.      * character set for echoing.
  197.      * <p>
  198.      * An echo character is useful for text fields where 
  199.      * user input should not be echoed to the screen, as in 
  200.      * the case of a text field for entering a password.
  201.      * @return     <code>true</code> if this text field has 
  202.      *                 a character set for echoing; 
  203.      *                 <code>false</code> otherwise.
  204.      * @see        java.awt.TextField#setEchoChar
  205.      * @see        java.awt.TextField#getEchoChar
  206.      * @since      JDK1.0
  207.      */
  208.     public boolean echoCharIsSet() {
  209.     return echoChar != 0;
  210.     }
  211.  
  212.     /**
  213.      * Gets the number of columns in this text field. 
  214.      * @return     the number of columns.
  215.      * @see        java.awt.TextField#setColumns
  216.      * @since      JDK1.1ld.
  217.      */
  218.     public int getColumns() {
  219.     return columns;
  220.     }
  221.  
  222.     /**
  223.      * Sets the number of columns in this text field.
  224.      * @param      columns   the number of columns.
  225.      * @see        java.awt.TextField#getColumns
  226.      * @exception  IllegalArgumentException   if the value
  227.      *                 supplied for <code>columns</code> 
  228.      *                 is less than zero.
  229.      * @since      JDK1.1
  230.      */
  231.     public synchronized void setColumns(int columns) {
  232.     int oldVal = this.columns;
  233.     if (columns < 0) {
  234.         throw new IllegalArgumentException("columns less than zero.");
  235.     }
  236.     if (columns != oldVal) {
  237.         this.columns = columns;
  238.         invalidate();
  239.     }
  240.     }
  241.  
  242.     /**
  243.      * Gets the preferred size of this text field 
  244.      * with the specified number of columns.
  245.      * @param     columns the number of columns 
  246.      *                 in this text field. 
  247.      * @return    the preferred dimensions for 
  248.      *                 displaying this text field.
  249.      * @since     JDK1.1
  250.      */
  251.     public Dimension getPreferredSize(int columns) {
  252.         synchronized (getTreeLock()) {
  253.             return preferredSize(columns);
  254.         }
  255.     }
  256.  
  257.     /**
  258.      * @deprecated As of JDK version 1.1,
  259.      * replaced by <code>getPreferredSize(int)</code>.
  260.      */
  261.     public Dimension preferredSize(int columns) {
  262.         synchronized (getTreeLock()) {
  263.         TextFieldPeer peer = (TextFieldPeer)this.peer;
  264.         return (peer != null) ?
  265.                peer.preferredSize(columns) :
  266.                super.preferredSize();
  267.         }
  268.     }
  269.  
  270.     /**
  271.      * Gets the preferred size of this text field. 
  272.      * @return     the preferred dimensions for 
  273.      *                         displaying this text field.
  274.      * @since      JDK1.1
  275.      */
  276.     public Dimension getPreferredSize() {
  277.         return preferredSize();
  278.     }
  279.  
  280.     /**
  281.      * @deprecated As of JDK version 1.1,
  282.      * replaced by <code>getPreferredSize()</code>.
  283.      */
  284.     public Dimension preferredSize() {
  285.         synchronized (getTreeLock()) {
  286.         return (columns > 0) ?
  287.                preferredSize(columns) :
  288.                super.preferredSize();
  289.         }
  290.     }
  291.  
  292.     /**
  293.      * Gets the minumum dimensions for a text field with 
  294.      * the specified number of columns.
  295.      * @param    columns   the number of columns in 
  296.      *                          this text field.
  297.      * @since    JDK1.1
  298.      */
  299.     public Dimension getMinimumSize(int columns) {
  300.         return minimumSize(columns);
  301.     }
  302.  
  303.     /**
  304.      * @deprecated As of JDK version 1.1,
  305.      * replaced by <code>getMinimumSize(int)</code>.
  306.      */
  307.     public Dimension minimumSize(int columns) {
  308.         synchronized (getTreeLock()) {
  309.         TextFieldPeer peer = (TextFieldPeer)this.peer;
  310.         return (peer != null) ?
  311.                peer.minimumSize(columns) :
  312.                super.minimumSize();
  313.         }
  314.     }
  315.  
  316.     /**
  317.      * Gets the minumum dimensions for this text field.
  318.      * @return     the minimum dimensions for 
  319.      *                  displaying this text field.
  320.      * @since      JDK1.1
  321.      */
  322.     public Dimension getMinimumSize() {
  323.         return minimumSize();
  324.     }
  325.  
  326.     /**
  327.      * @deprecated As of JDK version 1.1,
  328.      * replaced by <code>getMinimumSize()</code>.
  329.      */
  330.     public Dimension minimumSize() {
  331.         synchronized (getTreeLock()) {
  332.         return (columns > 0) ?
  333.                minimumSize(columns) :
  334.                super.minimumSize();
  335.         }
  336.     }
  337.  
  338.     /**
  339.      * Adds the specified action listener to recieve 
  340.      * action events from this text field.
  341.      * @param      l the action listener.
  342.      * @see        java.awt.event#ActionListener
  343.      * @see        java.awt.TextField#removeActionListener
  344.      * @since      JDK1.1
  345.      */ 
  346.     public synchronized void addActionListener(ActionListener l) {
  347.     actionListener = AWTEventMulticaster.add(actionListener, l);
  348.         newEventsOnly = true;    
  349.     }
  350.  
  351.     /**
  352.      * Removes the specified action listener so that it no longer
  353.      * receives action events from this text field.
  354.      * @param      l the action listener.
  355.      * @see        java.awt.event#ActionListener
  356.      * @see        java.awt.TextField#addActionListener
  357.      * @since      JDK1.1 
  358.      */ 
  359.     public synchronized void removeActionListener(ActionListener l) {
  360.     actionListener = AWTEventMulticaster.remove(actionListener, l);
  361.     }
  362.  
  363.     // REMIND: remove when filtering is done at lower level
  364.     boolean eventEnabled(AWTEvent e) {
  365.         if (e.id == ActionEvent.ACTION_PERFORMED) {
  366.             if ((eventMask & AWTEvent.ACTION_EVENT_MASK) != 0 ||
  367.                 actionListener != null) {
  368.                 return true;
  369.             } 
  370.             return false;
  371.         }
  372.         return super.eventEnabled(e);
  373.     }          
  374.  
  375.     /**
  376.      * Processes events on this text field. If the event 
  377.      * is an instance of <code>ActionEvent</code>,
  378.      * it invokes the <code>processActionEvent</code> 
  379.      * method. Otherwise, it invokes <code>processEvent</code> 
  380.      * on the superclass.
  381.      * @param      e the event.
  382.      * @see        java.awt.event.ActionEvent
  383.      * @see        java.awt.TextField#processActionEvent
  384.      * @since      JDK1.1
  385.      */
  386.     protected void processEvent(AWTEvent e) {
  387.         if (e instanceof ActionEvent) {
  388.             processActionEvent((ActionEvent)e);     
  389.             return;
  390.         }
  391.     super.processEvent(e);
  392.     }
  393.  
  394.     /** 
  395.      * Processes action events occurring on this text field by
  396.      * dispatching them to any registered 
  397.      * <code>ActionListener</code> objects. 
  398.      * <p>
  399.      * This method is not called unless action events are 
  400.      * enabled for this component. Action events are enabled 
  401.      * when one of the following occurs:
  402.      * <p><ul>
  403.      * <li>An <code>ActionListener</code> object is registered 
  404.      * via <code>addActionListener</code>.
  405.      * <li>Action events are enabled via <code>enableEvents</code>.
  406.      * </ul>
  407.      * @param       e the action event.
  408.      * @see         java.awt.event.ActionListener
  409.      * @see         java.awt.TextField#addActionListener
  410.      * @see         java.awt.Component#enableEvents
  411.      * @since       JDK1.1
  412.      */  
  413.     protected void processActionEvent(ActionEvent e) {
  414.         if (actionListener != null) {
  415.             actionListener.actionPerformed(e);
  416.         }
  417.     }
  418.  
  419.     /**
  420.      * Returns the parameter string representing the state of this 
  421.      * text field. This string is useful for debugging. 
  422.      * @return      the parameter string of this text field. 
  423.      * @since       JDK1.0
  424.      */
  425.     protected String paramString() {
  426.     String str = super.paramString();
  427.     if (echoChar != 0) {
  428.         str += ",echo=" + echoChar;
  429.     }
  430.     return str;
  431.     }
  432.  
  433.  
  434.     /* Serialization support. 
  435.      */
  436.  
  437.     private int textFieldSerializedDataVersion = 1;
  438.  
  439.  
  440.     private void writeObject(ObjectOutputStream s)
  441.       throws IOException 
  442.     {
  443.       s.defaultWriteObject();
  444.  
  445.       AWTEventMulticaster.save(s, actionListenerK, actionListener);
  446.       s.writeObject(null);
  447.     }
  448.  
  449.  
  450.     private void readObject(ObjectInputStream s)
  451.       throws ClassNotFoundException, IOException 
  452.     {
  453.       s.defaultReadObject();
  454.  
  455.       Object keyOrNull;
  456.       while(null != (keyOrNull = s.readObject())) {
  457.     String key = ((String)keyOrNull).intern();
  458.  
  459.     if (actionListenerK == key) 
  460.       addActionListener((ActionListener)(s.readObject()));
  461.  
  462.     else // skip value for unrecognized key
  463.       s.readObject();
  464.       }
  465.     }
  466.  
  467. }
  468.